Skip to content

docs: Add comprehensive thv build command documentation #116

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Open
wants to merge 4 commits into
base: main
Choose a base branch
from
Open

docs: Add comprehensive thv build command documentation #116

wants to merge 4 commits into from

Conversation

JAORMX
Copy link

@JAORMX JAORMX commented Aug 14, 2025

Summary

This PR adds comprehensive documentation for the thv build command, addressing issue #108.

What's being documented

New Documentation Files

📖 docs/toolhive/guides-cli/build-containers.mdx

  • Core thv build command usage and examples
  • Protocol scheme support (uvx://, npx://, go://)
  • Custom image tagging and Dockerfile generation
  • Kubernetes deployment workflows
  • Basic CI/CD integration patterns
  • Troubleshooting section with common issues

📖 docs/toolhive/guides-cli/advanced-cicd.mdx

  • Advanced CI/CD patterns for production environments
  • Multi-architecture builds with Docker Buildx
  • Supply chain security with SBOM, provenance, and signing
  • Efficient change detection strategies
  • Matrix builds for multiple MCP servers
  • Vulnerability scanning integration
  • GitLab CI examples

🔧 sidebars.ts

  • Added both new guides to the CLI guides section
  • Proper navigation structure and ordering

Key Features Covered

  • Protocol Schemes: Complete coverage of uvx://, npx://, and go:// schemes
  • Container Building: From basic usage to advanced production patterns
  • Kubernetes Integration: Pre-building containers for K8s deployments
  • CI/CD Workflows: GitHub Actions and GitLab CI examples
  • Security: Supply chain security, vulnerability scanning, and image signing
  • Best Practices: Production-ready patterns and troubleshooting guidance

Documentation Style

  • Follows established ToolHive documentation patterns
  • User-focused approach with practical examples
  • Clear separation between basic and advanced use cases
  • Comprehensive but not overwhelming
  • Includes proper cross-references and navigation

Closes #108

@JAORMX
docs: Add comprehensive thv build command documentation
3156cfa 
- Add build-containers.mdx guide covering thv build command usage
- Add advanced-cicd.mdx guide for production CI/CD patterns
- Update sidebar navigation to include both new guides
- Cover protocol schemes (uvx://, npx://, go://)
- Include Kubernetes deployment workflows
- Add troubleshooting section and best practices
- Include proper installation commands using GitHub releases

Closes #108
@Copilot Copilot AI review requested due to automatic review settings August 14, 2025 08:28
@vercel Vercel
Copy link

vercel bot commented Aug 14, 2025 •
edited
Loading

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Project Deployment Preview Comments Updated (UTC)
docs-website ✅ Ready Preview Comment Aug 14, 2025 1:40pm

Copilot
Copilot AI reviewed Aug 14, 2025
View reviewed changes
Copy link

@Copilot Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull Request Overview

This PR adds comprehensive documentation for the thv build command, addressing the need for detailed guidance on building MCP server containers without running them. The documentation is structured as two complementary guides that cover basic usage through advanced production patterns.

Key changes:

  • Added comprehensive thv build command documentation with practical examples
  • Created advanced CI/CD patterns guide for production environments
  • Integrated both guides into the CLI guides navigation structure

Reviewed Changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 4 comments.

File Description
sidebars.ts Added new CLI guides to the navigation sidebar
docs/toolhive/guides-cli/build-containers.mdx Comprehensive guide covering thv build basics, protocol schemes, Kubernetes workflows, and troubleshooting
docs/toolhive/guides-cli/advanced-cicd.mdx Advanced CI/CD patterns including multi-architecture builds, security scanning, and GitLab CI examples

@JAORMX
docs: Fix link anchor in build-containers.mdx
2e9b27b 
Remove fragment from thv run link as suggested by GitHub Copilot review
@JAORMX
docs: Fix ESLint errors in advanced-cicd.mdx
b4340c7 
Remove unused Tabs and TabItem imports that were causing lint failures
@JAORMX
Fix linter issues
bd1a8d2 
Signed-off-by: Juan Antonio Osorio <[email protected]>
@danbarr
Copy link
Collaborator

danbarr commented Aug 14, 2025

@claude please review this addition per the style guide @claude

@claude Claude
Copy link

claude bot commented Aug 14, 2025 •
edited
Loading

Claude finished @danbarr's task —— View job

Style Guide Review Complete ✅

I've thoroughly reviewed the new ToolHive build documentation against the repository's style guide. Overall, this is excellent documentation that follows most style guidelines correctly. Here's my detailed feedback:

✅ Style Guide Compliance - Strengths

Writing Style:

  • Excellent use of active voice throughout both documents
  • Consistent second-person address ("you", "your")
  • Casual yet professional tone that matches the style guide
  • Clear, straightforward language without excessive jargon
  • Proper sentence case in all headings
  • Correct capitalization of proper nouns (ToolHive, GitHub, Docker, etc.)

Content Structure:

  • Follows Diátaxis framework well - clear how-to guide structure
  • Logical progression from basic to advanced usage
  • Good separation of concerns between the two guides
  • Comprehensive but not overwhelming

Formatting:

  • Consistent use of monospace for commands, filenames, and code
  • Proper use of bold for UI elements and emphasis
  • Good use of code blocks with language specification
  • Clean markdown structure with proper spacing

🔧 Issues Requiring Fixes

Critical: Link Extension Issues (4 instances)

The Copilot review correctly identified link extension problems:

  1. Line 325 in build-containers.mdx: ../guides-k8s/run-mcp-k8s.md should be .mdx
  2. Line 333 in build-containers.mdx: ../guides-k8s/run-mcp-k8s.md should be .mdx
  3. Line 325 in advanced-cicd.mdx: ../guides-k8s/run-mcp-k8s.md should be .mdx

Per the style guide: "Use relative file links (with .md/.mdx extensions) when referring to other pages." Since the target file exists as .md, these should use .md extension, not .mdx.

Anchor Link Verification

Line 126 in build-containers.mdx: The link ./run-mcp-servers.mdx#run-a-server-using-protocol-schemes references a valid anchor - verified it exists in the target file.

📋 Minor Style Suggestions

  1. Consistent Protocol Naming: Both documents correctly maintain consistency in protocol scheme formatting (uvx://, npx://, go://)

  2. Command Examples: Excellent use of realistic, practical examples throughout

  3. Cross-references: Good use of relative links to maintain the documentation ecosystem

🎯 Content Quality Assessment

build-containers.mdx:

  • Comprehensive coverage of the thv build command
  • Excellent practical examples and use cases
  • Good troubleshooting section
  • Proper integration with existing documentation

advanced-cicd.mdx:

  • Advanced patterns are well-structured and practical
  • Good balance of GitHub Actions and GitLab CI examples
  • Security best practices are appropriately emphasized
  • Matrix build examples are particularly valuable

sidebars.ts:

  • Clean integration into existing navigation structure
  • Proper placement within CLI guides section

🚀 Recommendation

APPROVED with minor fixes required. The documentation is high-quality, well-structured, and follows the style guide effectively. Only the link extension corrections need to be addressed before merging.

Action Items

  • Fix 3 instances of .md extension in links to /guides-k8s/run-mcp-k8s.md
  • Run npm run markdownlint and npm run eslint to verify compliance

Review Tasks

  • Read repository style guide and CLAUDE.md files
  • Review build-containers.mdx for style compliance
  • Review advanced-cicd.mdx for style compliance
  • Review sidebars.ts changes
  • Analyze existing copilot feedback
  • Provide comprehensive style guide feedback

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

Copilot code review Copilot Copilot left review comments

At least 1 approving review is required to merge this pull request.

Assignees
No one assigned
Labels
None yet
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.

[CLI] Document thv build command (v0.2.3)
2 participants
@JAORMX @danbarr